Quality and Usability improvements
c_SSPInterface
The SSP interface is the only interface all client applications should use (there is still an exception for the Catalog request) and therefore it must be the most robust and fault tolerant interface of all.
The following guidelines should apply:
- Mandatory functions must always provide a functional response, so that the client application can handle the inability to function, where for instance menu items are not available, the client application should provide either a fallback or a clear message of the disfunctional of the portal application
- When there is technical error that prevents the fulfilment of a request the client application must be made aware that the outcome of the request is undecided and the response can't be trusted
- When there is a functional error the response should be in such a way that the client application can handle this functional response
- There is a difference noticable between no data available and no data because of an error
- Unexpected errors or errors that should/could be prevented must be log and that log must be monitored
- We should never rely on default behaviour of: ServiceNow, Javascript, Browsers etc. Always validate the availability of functionality before using it.
Most functions do not include a response result indicator, but show the resuls by the data objects it returns, as an improvement we should wrap the results in a resonse object that has (at least) the following:
- resultCode: Unique number for the result state, so that the client app can uniquely identify the situation, different methods do not need different resultcodes, so result codes identifies issues on the interface, not on the functionality
- resultMessage: Textual explanation of the error, specially crafted for the developers of the client application
- result: The actual response object which was requested
Optional properties
- uiMessage: Proposed UI message in the language of the user, to make it easier for the client application
- data